home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 3 / Cream of the Crop 3.iso / clipper / ks94an.zip / NEAREST.HDR < prev    next >
Text File  |  1994-04-25  |  4KB  |  132 lines
  1. /******************************************************************************
  2.                  The Klipper Library, for CA-Clipper 5.x
  3.         Copyright (c), 1994, Wallace Information Systems Engineering
  4.  
  5. FUNCTION:
  6.  
  7. _Nearest( nNum1, nNum2 nTarget, nRange )
  8.  
  9. PARAMETERS:
  10.  
  11. nNum1   : first number to test against nTarget
  12. nNum2   : second number to test against nTarget
  13. nTarget : nTarget (the number that nNum1 and nNum2 are tested against)
  14. nRange  : 0  = return nearest without EXceeding nTarget
  15.           1  = Return nearest (DEFAULT)
  16.           2  = Return nearest without PREceeding nTarget
  17.  
  18. SHORT:
  19.  
  20. Determine which of two values is closest to target value (with rules).
  21.  
  22. DESCRIPTION:
  23.  
  24. _Nearest() is a fairly complex function that compares nNum1 and nNum2 against
  25. nTarget and returns:
  26.  
  27. 1 - nNum1 is nearer to nTarget than nNum2 WITHIN the given rules
  28. 2 - nNum2 is nearer to nTarget than nNum1 WITHIN the given rules
  29. 0 - Neither number is closer to nTarget WITHIN the given rules because:
  30.  
  31.     EITHER : nNum1 and nNum2 BOTH exceed nTarget and nRange = LOW
  32.         OR : nNum1 and nNum2 BOTH preceede nTarget and nRange = HIGH
  33.         OR : nNum1 = nNum2
  34.         OR : (lower_num+n) = (higher_num-n) and RANGE = CLOSEST
  35.  
  36. Examples of conditions returning a value of 0:
  37.  
  38.     ************************ EX 1
  39.  
  40.  
  41.     nNum1   = 6
  42.     nTarget = 7
  43.     nNum2   = 8
  44.  
  45.     (6+1) = 7 = (8-1)
  46.  
  47.     ************************ EX 2
  48.  
  49.     nNum1   = 4
  50.     nTarget = 8
  51.     nNum2   = 12
  52.  
  53.     (4+4) = 8 = (12-4)
  54.  
  55.     ************************ EX 3
  56.  
  57.     nNum1   = 12
  58.     nTarget = 8
  59.     nNum2   = 4
  60.  
  61.     (12-4) = 8 = (4+4)
  62.  
  63.     In other words, Range = CLOSEST, but both numbers are equidistant from
  64. nTarget on opposite sides.  More examples follow.
  65.  
  66. NOTE:
  67.  
  68.  
  69.  
  70. EXAMPLE:
  71.  
  72. #define CLOSEST 0
  73. #define LOW     1
  74. #define HIGH    2
  75.  
  76.  
  77. ? 'CLOSEST EXAMPLES'
  78. ? '---------------------------------------------------------------'
  79.  
  80. ? _Nearest(3,4,5)         // 2 - Range Not specified so default is
  81. ? _Nearest(4,3,5)         // 1 - CLOSEST
  82.  
  83. ? _Nearest(3,4,5,CLOSEST) // 2 - These will be the same as above
  84. ? _Nearest(4,3,5,CLOSEST) // 1 - because of default to CLOSEST
  85.  
  86. ? _Nearest(4,4,5,CLOSEST) // 0 - nNum1 = nNum2 : neither are nearer
  87. ? _Nearest(5,5,5,CLOSEST) // 0 - ditto
  88.  
  89. ? 'HIGH EXAMPLES'
  90. ? '---------------------------------------------------------------'
  91.  
  92. ? _Nearest(9,12,10,HIGH)   // 2 - because 9 is lower than nTarget
  93. ? _Nearest(9,1000,10,HIGH) // 2 - ditto above
  94. ? _Nearest(8,9,10,HIGH)    // 0 - Both are below nTarget
  95.  
  96. ? 'LOW EXAMPLES'
  97. ? '---------------------------------------------------------------'
  98.  
  99. ? _Nearest(7,5,10,LOW)    // 1
  100. ? _Nearest(7,11,10,LOW)   // 1 - because 11 exceeds nTarget
  101. ? _Nearest(7,7,10,LOW)    // 0 - Both are equal
  102. ? _Nearest(6,7,10,LOW)    // 2
  103. ? _Nearest(17,18,10,LOW)  // 0 - Both exceed nTarget
  104. ? _Nearest(17,17,10,LOW)  // 0 - Both equal/exceed nTarget
  105.  
  106. ? 'EQUALITY EXAMPLES - not equal to each other but from nTarget'
  107. ? '---------------------------------------------------------------'
  108.  
  109. ? _Nearest(5,7,6,CLOSEST)   // All these return 0
  110. ? _Nearest(4,6,5,CLOSEST)   //
  111. ? _Nearest(13,7,10,CLOSEST) //
  112. ? _Nearest(7,13,10,CLOSEST) //
  113.  
  114. ? 'MORE EXAMPLES'
  115. ? '---------------------------------------------------------------'
  116.  
  117. ? _Nearest(4,4,5)      // 0 neither is nearer than the other
  118. ? _Nearest(4.1,3,5)    // 1
  119. ? _Nearest(3,6,5)      // 2
  120. ? _Nearest(3,6,5,LOW)  // 1 (nNum2 exceeds nTarget)
  121. ? _Nearest(6,3,5,LOW)  // 2 (nNum1 exceeds nTarget)
  122.  
  123.  
  124. Note that _Nearest() will also accept dates in place of nNum1, nNum2
  125. and nTarget:
  126.  
  127. t = _Nearest(ctod('01/21/93), ctod('01/26/93'), ctod('01/25/93'), LOW)
  128.  
  129. Result: t = 1 // because 01/26/93 exceeds target date and Range = LOW
  130.  
  131. ******************************************************************************/
  132.